Crate handlebars[−][src]

Handlebars

Handlebars is a modern and extensible templating solution originally created in the JavaScript world. It’s used by many popular frameworks like Ember.js and Chaplin. It’s also ported to some other platforms such as Java.

And this is handlebars Rust implementation, designed for general purpose text generation.

Quick Start

use std::collections::BTreeMap;
use handlebars::Handlebars;

fn main() {
  // create the handlebars registry
  let mut handlebars = Handlebars::new();

  // register the template. The template string will be verified and compiled.
  let source = "hello {{world}}";
  assert!(handlebars.register_template_string("t1", source).is_ok());

  // Prepare some data.
  //
  // The data type should implements `serde::Serialize`
  let mut data = BTreeMap::new();
  data.insert("world".to_string(), "世界!".to_string());
  assert_eq!(handlebars.render("t1", &data).unwrap(), "hello 世界!");
}

In this example, we created a template registry and registered a template named t1. Then we rendered a BTreeMap with an entry of key world, the result is just what we expected.

I recommend you to walk through handlebars.js’ intro page if you are not quite familiar with the template language itself.

Features

Handlebars is a real-world templating system that you can use to build your application without pain.

Isolation of Rust and HTML

This library doesn’t attempt to use some macro magic to allow you to write your template within your rust code. I admit that it’s fun to do that but it doesn’t fit real-world use cases.

Limited but essential control structures built-in

Only essential control directives if and each are built-in. This prevents you from putting too much application logic into your template.

Extensible helper system

You can write your own helper with Rust! It can be a block helper or inline helper. Put your logic into the helper and don’t repeat yourself.

The built-in helpers like if and each were written with these helper APIs and the APIs are fully available to developers.

Template inheritance

Every time I look into a templating system, I will investigate its support for template inheritance.

Template include is not sufficient for template reuse. In most cases you will need a skeleton of page as parent (header, footer, etc.), and embed your page into this parent.

You can find a real example of template inheritance in examples/partials.rs and templates used by this file.

Strict mode

Handlebars, the language designed to work with JavaScript, has no strict restriction on accessing nonexistent fields or indexes. It generates empty strings for such cases. However, in Rust we want to be a little stricter sometimes.

By enabling strict_mode on handlebars:

handlebars.set_strict_mode(true);

You will get a RenderError when accessing fields that do not exist.

Limitations

Compatibility with original JavaScript version

This implementation is not fully compatible with the original JavaScript version.

First of all, mustache blocks are not supported. I suggest you to use #if and #each for the same functionality.

There are some other minor features missing:

Chained else #12

Feel free to file an issue on github if you find missing features.

Types

As a static typed language, it’s a little verbose to use handlebars. Handlebars templating language is designed against JSON data type. In rust, we will convert user’s structs, vectors or maps into Serde-Json’s Value type in order to use in templates. You have to make sure your data implements the Serialize trait from the Serde project.

Usage

Template Creation and Registration

Templates are created from Strings and registered to Handlebars with a name.


use handlebars::Handlebars;

  let mut handlebars = Handlebars::new();
  let source = "hello {{world}}";

  assert!(handlebars.register_template_string("t1", source).is_ok())

On registration, the template is parsed, compiled and cached in the registry. So further usage will benefit from the one-time work. Also features like include, inheritance that involves template reference requires you to register those template first with a name so the registry can find it.

If you template is small or just to experiment, you can use render_template API without registration.

use handlebars::Handlebars;
use std::collections::BTreeMap;

  let mut handlebars = Handlebars::new();
  let source = "hello {{world}}";

  let mut data = BTreeMap::new();
  data.insert("world".to_string(), "世界!".to_string());
  assert_eq!(handlebars.render_template(source, &data)?, "hello 世界!".to_owned());

Rendering Something

Since handlebars is originally based on JavaScript type system. It supports dynamic features like duck-typing, truthy/falsey values. But for a static language like Rust, this is a little difficult. As a solution, we are using the serde_json::value::Value internally for data rendering.

That means, if you want to render something, you have to ensure the data type implements the serde::Serialize trait. Most rust internal types already have that trait. Use #derive[Serialize] for your types to generate default implementation.

You can use default render function to render a template into String. From 0.9, there’s render_to_write to render text into anything of std::io::Write.


use handlebars::Handlebars;

#[derive(Serialize)]
struct Person {
  name: String,
  age: i16,
}

  let source = "Hello, {{name}}";

  let mut handlebars = Handlebars::new();
  assert!(handlebars.register_template_string("hello", source).is_ok());


  let data = Person {
      name: "Ning Sun".to_string(),
      age: 27
  };
  assert_eq!(handlebars.render("hello", &data)?, "Hello, Ning Sun".to_owned());

Or if you don’t need the template to be cached or referenced by other ones, you can simply render it without registering.

use handlebars::Handlebars;

  let source = "Hello, {{name}}";

  let mut handlebars = Handlebars::new();

  let data = Person {
      name: "Ning Sun".to_string(),
      age: 27
  };
  assert_eq!(handlebars.render_template("Hello, {{name}}", &data)?,
      "Hello, Ning Sun".to_owned());

Escaping

As per the handlebars spec, output using {{expression}} is escaped by default (to be precise, the characters &"<> are replaced by their respective html / xml entities). However, since the use cases of a rust template engine are probably a bit more diverse than those of a JavaScript one, this implementation allows the user to supply a custom escape function to be used instead. For more information see the EscapeFn type and Handlebars::register_escape_fn() method.

Custom Helper

Handlebars is nothing without helpers. You can also create your own helpers with rust. Helpers in handlebars-rust are custom struct implements the HelperDef trait, concretely, the call function. For your convenience, most of stateless helpers can be implemented as bare functions.

use std::io::Write;
use handlebars::{Handlebars, HelperDef, RenderContext, Helper, Context, JsonRender, HelperResult, Output, RenderError};

// implement by a structure impls HelperDef
#[derive(Clone, Copy)]
struct SimpleHelper;

impl HelperDef for SimpleHelper {
  fn call<'reg: 'rc, 'rc>(&self, h: &Helper, _: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut dyn Output) -> HelperResult {
    let param = h.param(0).unwrap();

    out.write("1st helper: ")?;
    out.write(param.value().render().as_ref())?;
    Ok(())
  }
}

// implement via bare function
fn another_simple_helper (h: &Helper, _: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut dyn Output) -> HelperResult {
    let param = h.param(0).unwrap();

    out.write("2nd helper: ")?;
    out.write(param.value().render().as_ref())?;
    Ok(())
}


  let mut handlebars = Handlebars::new();
  handlebars.register_helper("simple-helper", Box::new(SimpleHelper));
  handlebars.register_helper("another-simple-helper", Box::new(another_simple_helper));
  // via closure
  handlebars.register_helper("closure-helper",
      Box::new(|h: &Helper, r: &Handlebars, _: &Context, rc: &mut RenderContext, out: &mut dyn Output| -> HelperResult {
          let param = h.param(0).ok_or(RenderError::new("param not found"))?;

          out.write("3rd helper: ")?;
          out.write(param.value().render().as_ref())?;
          Ok(())
      }));

  let tpl = "{{simple-helper 1}}\n{{another-simple-helper 2}}\n{{closure-helper 3}}";
  assert_eq!(handlebars.render_template(tpl, &())?,
      "1st helper: 1\n2nd helper: 2\n3rd helper: 3".to_owned());

Data available to helper can be found in Helper. And there are more examples in HelperDef page.

You can learn more about helpers by looking into source code of built-in helpers.

Script Helper

Like our JavaScript counterparts, handlebars allows user to define simple helpers with a scripting language, rhai. This can be enabled by turning on script_helper feature flag.

A sample script:

{{percent 0.34 label="%"}}

// percent.rhai
// get first parameter from `params` array
let value = params[0];
// get key  value pair `label` from `hash` map
let label = hash["label"];

// compute the final string presentation
(value * 100).to_string() + label

A runnable example can be find in the repo.

Built-in Helpers

{{{{raw}}}} ... {{{{/raw}}}} escape handlebars expression within the block
{{#if ...}} ... {{else}} ... {{/if}} if-else block
{{#unless ...}} ... {{else}} .. {{/unless}} if-not-else block
{{#each ...}} ... {{/each}} iterates over an array or object. Handlebars-rust doesn’t support mustache iteration syntax so use this instead.
{{#with ...}} ... {{/with}} change current context. Similar to {{#each}}, used for replace corresponding mustache syntax.
{{lookup ... ...}} get value from array by @index or @key
{{> ...}} include template with name
{{log ...}} log value with rust logger, default level: INFO. Currently you cannot change the level.
Boolean helpers that can be used in if as subexpression, for example {{#if (gt 2 1)}} ...:
- eq
- ne
- gt
- gte
- lt
- lte
- and
- or
- not

debug	This macro is defined if the `logging` feature is set.
error	This macro is defined if the `logging` feature is not set.
handlebars_helper	Macro that allows you to quickly define a handlebars helper by passing a name and a closure.
info	This macro is defined if the `logging` feature is not set.
log	This macro is defined if the `logging` feature is not set.
trace	This macro is defined if the `logging` feature is not set.
warn	This macro is defined if the `logging` feature is not set.

Structs

BlockContext	A data structure holds contextual data for current block scope.
BlockParams	A map holds block parameters. The parameter can be either a value or a reference
Context	The context wrap data you render on your templates.
Decorator	Render-time Decorator data when using in a decorator definition
Handlebars	The single entry point of your Handlebars templates
Helper	Render-time Helper data when using in a helper definition
PathAndJson	Json wrapper that holds the Json value and reference path information
RenderContext	The context of a render call
RenderError	Error when rendering data on template.
TemplateError	Error on parsing template.

Enums

Path	Represents the Json path in templates.
ScopedJson	A JSON wrapper designed for handlebars internal use case
TemplateFileError	A combined error type for `TemplateError` and `IOError`
TemplateRenderError	A combined error type for `TemplateError`, `IOError` and `RenderError`

Traits

DecoratorDef	Decorator Definition
Evaluable	Evaluate decorator
HelperDef	Helper Definition
JsonRender	Render Json data with default format
Output	The Output API.
Renderable	Render trait

Functions

html_escape	The default escape fn replaces the characters `&"<>` with the equivalent html / xml entities.
no_escape	`EscapeFn` that does not change anything. Useful when using in a non-html environment.
to_json	Convert any serializable data into Serde Json type

Type Definitions

EscapeFn	This type represents an escape fn, that is a function whose purpose it is to escape potentially problematic characters in a string.
HelperResult	A type alias for `Result<(), RenderError>`

Crate handlebars[−][src]

Handlebars

Quick Start

Features

Isolation of Rust and HTML

Limited but essential control structures built-in

Extensible helper system

Template inheritance

Strict mode

Limitations

Compatibility with original JavaScript version

Types

Usage

Template Creation and Registration

Rendering Something

Escaping

Custom Helper

Script Helper

Built-in Helpers

Template inheritance

Re-exports

Modules

Macros

Structs

Enums

Traits

Functions

Type Definitions

Crate handlebars⎘[−][src]

Crate handlebars[−][src]